home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 November: Tool Chest / Dev.CD Nov 94.toast / Apple II / Essentials / Essentials.sea / File.Type.Notes / FTN.C0.0002 < prev    next >
Encoding:
Text File  |  1993-06-15  |  8.4 KB  |  188 lines  |  [TEXT/pdos]
  1. Apple II
  2. File Type Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. File Type:         $C0 (192)
  7. Auxiliary Type:    $0002
  8.  
  9. Full Name:     Apple IIgs Super Hi-Res Picture File
  10. Short Name:    "Apple Preferred" Picture
  11.  
  12. Revised by:    Matt Deatherage                                  December 1991
  13. Written by:    Steve Glass, Eagle Berns, Art Cabral              October 1987
  14.                & Pete McDonald
  15.  
  16. Files of this type and auxiliary type contain a Super Hi-Res picture in the 
  17. Apple-recommended format.
  18. Changes since September 1990:  Added a recommeendation for more conventional
  19. respresentation of 3200-color pictures.
  20. _____________________________________________________________________________
  21.  
  22. Files of type $C0 and auxiliary type $0002 contain a Super Hi-Res picture in 
  23. the format recommended by Apple.  The file consists of a series of variable-
  24. length blocks (in any order), each with the same general format:
  25.  
  26.     Length               Long    Defines the length of this block, 
  27.                                  including Length itself.
  28.     Kind                 String  String used to identify the type of 
  29.                                  block.  The string is stored as a 
  30.                                  series of case-sensitive ASCII 
  31.                                  characters preceded by a length 
  32.                                  byte.  To avoid confusion, the use 
  33.                                  of uppercase characters only is 
  34.                                  recommended.
  35.     Data                 Bytes   Variable amount of block-specific 
  36.                                  data.
  37.  
  38. With this scheme, the file format is flexible and can be extended.  Standard 
  39. blocks which most applications want are defined below, however, these are not 
  40. required.  Individual applications can define other blocks.  Application-
  41. dependent information can be stored to allow other applications to ignore it.  
  42. Your application should simply ignore blocks it finds which it is not prepared 
  43. to interpret.
  44.  
  45. Data Types
  46.  
  47.     Integer              16-bit signed word.
  48.     LongInt              32-bit signed long word.
  49.     ColorEntry           16-bit word. The nibbles in the word are 
  50.                          interpreted as RGB values as follows:  $0RGB.  
  51.                          The high nibble of the high byte must be zero 
  52.                          and should be ignored when reading files.  The 
  53.                          low nibble of the high byte is the value for 
  54.                          red, the high nibble of the low byte is the 
  55.                          value for green, and the low nibble of the low 
  56.                          byte is the value for blue (see Figure 16-19 on 
  57.                          page 16-31 of the Apple IIgs Toolbox Reference).
  58.     ColorTable           16 words:  array [0..15] of ColorEntry
  59.     ModeWord             16-bit word.  The high byte determines the 
  60.                          definition of the mode. If high byte = 0, then 
  61.                          the low byte is the mode bit portion of the SCB 
  62.                          for the scan line  (see Figure 16-22 on page 16-
  63.                          34 of the Apple IIgs Toolbox Reference).  Other 
  64.                          bits are reserved and must be zero, as other 
  65.                          modes are not yet defined.
  66.     DirEntry             A two-word structure used to define the 
  67.                          characteristics of each packed line:
  68.                              Integer:     Number of bytes to unpack
  69.                              ModeWord:    Mode
  70.     PatternData          32 bytes of pattern information
  71.  
  72.  
  73. MAIN Information Block
  74.  
  75. Every file usually, but not necessarily (i.e., a file of palettes only), 
  76. includes a MAIN block.
  77.  
  78.     Length               LongInt
  79.     Kind                 String "MAIN"
  80.     MasterMode           ModeWord (from the MasterSCB of QuickDraw II.  
  81.                          When reading a file, this word should 
  82.                          be used in a SetMasterSCB call.)
  83.     PixelsPerScanLine    Integer (must not be zero)
  84.     NumColorTables       Integer (may be zero)
  85.     ColorTableArray      [0..NumColorTables-1] of ColorTable
  86.     NumScanLines         Integer (must not be zero)
  87.     ScanLineDirectory    [0..NumScanLines-1] of DirEntry
  88.     PackedScanlines      [0..NumScanLines-1] of Packed Data 
  89.                          (Obtained by performing a PackBytes call 
  90.                          on the pixel image of a single scan line.)
  91.  
  92.  
  93. PATS Information Block
  94.  
  95. The PATS block contains patterns which may be associated with the picture.
  96.  
  97.     Length               LongInt
  98.     Kind                 String "PATS"
  99.     NumPats              Integer
  100.     PatternArray         [0..NumPats-1] of PatternData
  101.  
  102.  
  103. SCIB Information Block
  104.  
  105. The SCIB block contains information relating to the current drawing pattern 
  106. for the document.  This information is used by paint programs that want to 
  107. save a foreground pattern, a background pattern, and a frame pattern with the 
  108. image.
  109.  
  110.     Length               LongInt
  111.     Kind                 String "SCIB"
  112.     ForegroundPattern    PatternData
  113.     BackgroundPattern    PatternData
  114.     FramePattern         PatternData
  115.  
  116.  
  117. PALETTES Information Block
  118.  
  119. The PALETTES block contains information on the color tables.  Its use is 
  120. intended for color table files.  If the file being saved contains a pixel 
  121. image, then the color tables associated with that picture should be saved in 
  122. the MAIN block, and this block would not be used.
  123.  
  124.     Length               LongInt
  125.     Kind                 String "PALETTES"
  126.     NumColorTables       Integer (must not be zero)
  127.     ColorTableArray      [0..NumPalettes-1] of ColorTable
  128.  
  129.  
  130. Other Information Blocks
  131.  
  132. Apple Preferred Format is an extensible graphics file format.  Since its 
  133. release, some developers have contributed other block definitions that other 
  134. developers may find to be useful.  Please feel free to incorporate these 
  135. blocks into Apple Preferred files, but you must be prepared to deal with Apple 
  136. Preferred files that do not contain these additional blocks.
  137.  
  138. MASK Information Block
  139.  
  140. The MASK block contains information on which portions of a graphic image 
  141. should be modified.  The structure is similar to that of the MAIN block.  
  142. However, the MASK array of PackedScanLines contains zeroes where no drawing is 
  143. to occur (where the image is transparent) and ones where drawing may occur 
  144. (where the image is solid).  The structural similarity to the MAIN block can 
  145. help by allowing some of your code to do double work.
  146.  
  147.     Length               LongInt
  148.     Kind                 String "MASK"
  149.     MasterMode           ModeWord (from the MasterSCB of QuickDraw II.  
  150.                          When reading a file, this word should 
  151.                          be used in a SetMasterSCB call.)
  152.     PixelsPerScanLine    Integer (must not be zero)
  153.     NumColorTables       Integer (must be zero)
  154.     NumScanLines         Integer (must not be zero)
  155.     ScanLineDirectory    [0..NumScanLines-1] of DirEntry
  156.     PackedScanlines      [0..NumScanLines-1] of Packed Data 
  157.                          (Obtained by performing a PackBytes call 
  158.                          on the pixel image of a single scan line.)
  159.  
  160.     Note:  There is no ColorTableArray, as indicated by a zero value 
  161.            in NumColorTables.
  162.     Note:  The scan lines to be packed should only contain mask values 
  163.            of one and zero.
  164.  
  165. MULTIPAL Information Block
  166.  
  167. The MUTLIPAL block contains extra color tables necessary for displaying 
  168. pictures that contain up to 3,200 colors on the screen.
  169.  
  170.     Length               LongInt
  171.     Kind                 String "MULTIPAL"
  172.     NumColorTables       Integer (should be the same as NumScanLines 
  173.                          in MAIN).  This is typically 200, but any value 
  174.                          is legal.
  175.     ColorTableArray      [0..NumColorTables-1] of ColorTable.  
  176.                          These are in the regular (0-15) order.
  177.  
  178. If you use the MULTIPAL block to store pictures with more colors than are
  179. typically displayable on the screen, Apple recommends you also create a MAIN
  180. block with a 16-color (or grayscale) representation of the picture, so users
  181. may open these files in les specialized applications to at least preview the
  182. picture enclosed.
  183.  
  184. Further Reference
  185. _____________________________________________________________________________
  186.   o  Apple IIgs Toolbox Reference
  187.   o  Apple IIgs Technical Note #94, Packing It In (and Out)
  188.